//
// Created by Administrator on 2025/8/20.
//

#ifndef INC_12_FREERTOS_LWIP_MQTT_NEWLAND_SQLIST_H
#define INC_12_FREERTOS_LWIP_MQTT_NEWLAND_SQLIST_H
#include "main.h"

// FreeRTOS includes
#include "FreeRTOS.h"
#include "semphr.h"
#include "task.h" // For size_t with some compilers

/**
 * @brief 定义一个支持泛型、线程安全的顺序表结构体
 */
typedef struct {
    void *data;                 // 指向通用数据数组的指针
    size_t size;                // 当前列表中的元素数量
    size_t capacity;            // 列表的已分配容量
    size_t element_size;        // 每个元素的字节大小
    SemaphoreHandle_t mutex;    // 用于线程安全访问的互斥锁
} SeqList_t;

// Function Prototypes

/**
 * @brief 初始化一个顺序表
 * @param sl 指向 SeqList_t 结构体的指针
 * @param element_size 要存储的每个元素的字节大小
 * @return pdPASS 表示成功, pdFAIL 表示失败 (例如，内存分配失败)
 */
BaseType_t SeqList_Init(SeqList_t *sl, size_t element_size);

/**
 * @brief 销毁一个顺序表，释放所有已分配的资源
 * @param sl 指向 SeqList_t 结构体的指针
 */
void SeqList_Destory(SeqList_t *sl);

/**
 * @brief 在列表末尾添加一个元素
 * @param sl 指向 SeqList_t 结构体的指针
 * @param item 指向要添加的元素的指针
 */
void SeqList_PushBack(SeqList_t *sl, const void *item);

/**
 * @brief 在列表头部添加一个元素
 * @param sl 指向 SeqList_t 结构体的指针
 * @param item 指向要添加的元素的指针
 */
void SeqList_PushFront(SeqList_t *sl, const void *item);

/**
 * @brief 从列表末尾移除一个元素
 * @param sl 指向 SeqList_t 结构体的指针
 */
void SeqList_PopBack(SeqList_t *sl);

/**
 * @brief 从列表头部移除一个元素
 * @param sl 指向 SeqList_t 结构体的指针
 */
void SeqList_PopFront(SeqList_t *sl);

/**
 * @brief 使用用户提供的打印函数打印列表中的所有元素
 * @param sl 指向 SeqList_t 结构体的指针
 * @param print_func 一个函数指针，该函数知道如何打印单个元素
 */
void SeqList_Print(const SeqList_t *sl, void (*print_func)(const void *item));

BaseType_t SeqList_Get(const SeqList_t *sl, size_t index, void *out_item);

BaseType_t SeqList_Get_Size(const SeqList_t *sl,uint8_t *size);
#endif //INC_12_FREERTOS_LWIP_MQTT_NEWLAND_SQLIST_H